LineRenderer3D.java

/* ===========================================================

 * Orson Charts : a 3D chart library for the Java(tm) platform

 * ===========================================================

 * 

 * (C)opyright 2013-2020, by Object Refinery Limited.  All rights reserved.

 * 

 * https://github.com/jfree/orson-charts

 * 

 * This program is free software: you can redistribute it and/or modify

 * it under the terms of the GNU General Public License as published by

 * the Free Software Foundation, either version 3 of the License, or

 * (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program.  If not, see <http://www.gnu.org/licenses/>.

 * 

 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 

 * Other names may be trademarks of their respective owners.]

 * 

 * If you do not wish to be bound by the terms of the GPL, an alternative

 * commercial license can be purchased.  For details, please see visit the

 * Orson Charts home page:

 * 

 * http://www.object-refinery.com/orsoncharts/index.html

 * 

 */

package org.jfree.chart3d.renderer.category;

import java.awt.Color;

import java.io.Serializable;

import org.jfree.chart3d.Chart3D;

import org.jfree.chart3d.Chart3DFactory;

import org.jfree.chart3d.axis.CategoryAxis3D;

import org.jfree.chart3d.axis.ValueAxis3D;

import org.jfree.chart3d.data.KeyedValues3DItemKey;

import org.jfree.chart3d.data.Range;

import org.jfree.chart3d.data.category.CategoryDataset3D;

import org.jfree.chart3d.graphics3d.Dimension3D;

import org.jfree.chart3d.graphics3d.Object3D;

import org.jfree.chart3d.graphics3d.Offset3D;

import org.jfree.chart3d.graphics3d.World;

import org.jfree.chart3d.internal.ObjectUtils;

import org.jfree.chart3d.label.ItemLabelPositioning;

import org.jfree.chart3d.plot.CategoryPlot3D;

import org.jfree.chart3d.renderer.Renderer3DChangeEvent;

/**

 * A renderer that can be used with the {@link CategoryPlot3D} class to create

 * 3D lines charts from data in a {@link CategoryDataset3D}.  The 

 * {@code createLineChart()} method in the {@link Chart3DFactory} class 

 * will construct a chart that uses this renderer.  Here is a sample:

 * <div>

 * <img src="../../../../../../doc-files/LineChart3DDemo1.svg" 

 * alt="LineChart3DDemo1.svg" width="500" height="359">

 * </div>

 * (refer to {@code LineChart3DDemo1.java} for the code to generate the

 * above chart).

 * <br><br>

 * Some attributes in the renderer are specified in "world units" - see the

 * {@link Chart3D} class description for more information about world units.

 * <br><br>

 * There is a factory method to create a chart using this renderer - see

 * {@link Chart3DFactory#createLineChart(String, String, CategoryDataset3D, 

 * String, String, String)}.

 * <br><br> 

 * NOTE: This class is serializable, but the serialization format is subject 

 * to change in future releases and should not be relied upon for persisting 

 * instances of this class.

 */

@SuppressWarnings("serial")

public class LineRenderer3D extends AbstractCategoryRenderer3D 

        implements Serializable {

    /** The line width (in world units). */

    private double lineWidth;

    /** The line height (in world units). */

    private double lineHeight;

    /** 

     * For isolated data values this attribute controls the width (x-axis) of 

     * the box representing the data item, it is expressed as a percentage of

     * the category width.

     */

    private double isolatedItemWidthPercent;

    /**

     * The color source that determines the color used to highlight clipped

     * items in the chart.

     */

    private CategoryColorSource clipColorSource;

    /**

     * Creates a new instance with default attribute values.

     */

    /**

     * Returns the line width in world units.  The default value is 

     * {@code 0.4}.

     * 

     * @return The line width in world units. 

     */

    public double getLineWidth() {

    }

    /**

     * Sets the line width (in world units) and sends a 

     * {@link Renderer3DChangeEvent} to all registered listeners.

     * 

     * @param width  the width (in world units). 

     */

    public void setLineWidth(double width) {

    /**

     * Returns the line height in world units.  The default value is 

     * {@code 0.2}.

     * 

     * @return The line height in world units. 

     */

    public double getLineHeight() {

    }

    /**

     * Sets the line height (in world units) and sends a 

     * {@link Renderer3DChangeEvent} to all registered listeners.

     * 

     * @param height  the height (in world units). 

     */

    public void setLineHeight(double height) {

    /**

     * Returns the width for isolated data items as a percentage of the

     * category width.  The default value is 0.25 (twenty five percent).

     * 

     * @return The width percentage.

     * 

     * @since 1.3

     */

    public double getIsolatedItemWidthPercent() {

    }

    /**

     * Sets the width for isolated data items as a percentage of the category

     * width and sends a change event to all registered listeners.

     * 

     * @param percent  the new percentage.

     * 

     * @since 1.3

     */

    public void setIsolatedItemWidthPercent(double percent) {

    /**

     * Returns the color source used to determine the color used to highlight

     * clipping in the chart elements.  If the source is {@code null},

     * then the regular series color is used instead.

     * 

     * @return The color source (possibly {@code null}). 

     */

    public CategoryColorSource getClipColorSource() {

    }

    /**

     * Sets the color source that determines the color used to highlight

     * clipping in the chart elements, and sends a {@link Renderer3DChangeEvent}

     * to all registered listeners.

     * 

     * @param source  the source ({@code null} permitted). 

     */

    public void setClipColorSource(CategoryColorSource source) {

    /**

     * Constructs and places one item from the specified dataset into the given 

     * world.  This method will be called by the {@link CategoryPlot3D} class

     * while iterating over the items in the dataset.

     * 

     * @param dataset  the dataset ({@code null} not permitted).

     * @param series  the series index.

     * @param row  the row index.

     * @param column  the column index.

     * @param world  the world ({@code null} not permitted).

     * @param dimensions  the plot dimensions ({@code null} not permitted).

     * @param xOffset  the x-offset.

     * @param yOffset  the y-offset.

     * @param zOffset  the z-offset.

     */

    @Override

    @SuppressWarnings("unchecked")

    public void composeItem(CategoryDataset3D dataset, int series, int row, 

            int column, World world, Dimension3D dimensions, 

            double xOffset, double yOffset, double zOffset) {

        // there is a lot of brute force code underneath this compose method

        // because I haven't seen the pattern yet that will let me reduce it

        // to something more elegant...probably I'm not smart enough.

        }

        }

        // for any data value, we'll try to create two line segments, one to

        // the left of the value and one to the right of the value (each 

        // halfway to the adjacent data value).  If the adjacent data values

        // are null (or don't exist, as in the case of the first and last data

        // items, then we can create an isolated segment to represent the data

        // item.  The final consideration is whether the opening and closing

        // faces of each segment are filled or not (if the segment connects to

        // another segment, there is no need to fill the end face)

        boolean createLeftSegment, createRightSegment, createIsolatedSegment;

            } else {

            }

        } else { // this is the general case

                    && yprev == null && ynext == null);

        }

        // now that we know what we have to create, we'll need some info 

        // for the construction

        }

            }

        }

                rowKey, columnKey);

                    ww) + xOffset;

                    + yOffset; 

                    this.lineHeight, ywmin, ywmax, color, clipColor, leftOpen, 

                    leftClose);

            }

        }

                    ww) + xOffset;

                    + yOffset; 

                    this.lineHeight, ywmin, ywmax, color, clipColor, rightOpen, 

                    rightClose);

            }

        }

                    * this.isolatedItemWidthPercent;

                    zw, this.lineWidth, color);

            }

        }

                && yw >= ywmin && yw <= ywmax) {

                    seriesKey, rowKey, columnKey);

                            xw, yw + dy, zw, false, true);

                        ItemLabelPositioning.FRONT_AND_BACK)) {

                            xw, yw, zw - dz, false, false);

                            xw, yw, zw + dz, true, false);

                }

            }

        }

    /**

     * Creates a segment of a line between (x0, y0, z) and (x1, y1, z), with

     * the specified line width and height, taking into account the minimum

     * and maximum world coordinates (in the y-direction, because it is assumed

     * that we have the full x and z-range required).

     * 

     * @param x0  the starting x-coordinate.

     * @param y0  the starting x-coordinate.

     * @param x1  the ending x-coordinate.

     * @param y1  the ending y-coordinate.

     * @param z  the z-coordinate.

     * @param lineWidth  the line width (z-axis).

     * @param lineHeight  the line height (y-axis).

     * @param ymin  the lower bound for y-values.

     * @param ymax  the upper bound for y-values.

     * @param color  the segment color.

     * @param clipColor  the clip color (for the faces in the segment that are

     *     clipped against the edge of the world).

     * @param openingFace  is an opening face required?

     * @param closingFace  is a closing face required?

     * 

     * @return A 3D object that is a segment in a line.

     */

    private Object3D createSegment(double x0, double y0, double x1, double y1,

            double z, double lineWidth, double lineHeight, double ymin, 

            double ymax, Color color, Color clipColor, boolean openingFace,

            boolean closingFace) {

            ymin, ymax, zf, zb, color, clipColor, false, closingFace);

                    zf, zb, color, clipColor, openingFace, closingFace);

                    zf, zb, color, clipColor, openingFace, closingFace);

                    zf, zb, color, clipColor, openingFace, closingFace);                    

                    zf, zb, color, clipColor, openingFace, closingFace);                    

                    zf, zb, color, clipColor, false, closingFace);                   

        }

    }

    /**

     * Calculates the four intersection points between two horizontal lines

     * (ymin and ymax) and the lines (x0, y0b, x1, y1b) and (x0, y1t, x1, y1t)

     * and returns the x-coordinates in an array.

     * 

     * @param x0

     * @param x1

     * @param y0b

     * @param y0t

     * @param y1b

     * @param y1t

     * @param ymin

     * @param ymax

     * 

     * @return An array of 4 x-coordinates. 

     */

    private double[] calcCrossPoints(double x0, double x1, double y0b, 

            double y0t, double y1b, double y1t, double ymin, double ymax) {

            Double.NaN };

    }

    /**

     * Creates a segment for the case where the start of the segment is 

     * completely above the upper bound of the axis at the left side of the

     * chart.

     * 

     * @param x0

     * @param x1

     * @param xpts

     * @param y0b

     * @param y0t

     * @param y1b

     * @param y1t

     * @param wmin

     * @param wmax

     * @param zf

     * @param zb

     * @param color

     * @param clipColor

     * @param openingFace  ignored because there is no opening face for this

     *     case.

     * @param closingFace

     * 

     * @return A segment ({@code null} if the segment is entirely clipped). 

     */

    private Object3D createSegmentA(double x0, double x1, double[] xpts, 

            double y0b, double y0t, double y1b, double y1t, double wmin, 

            double wmax, double zf, double zb, Color color, Color clipColor, 

            boolean openingFace, boolean closingFace) {

        }

                // create a triangle with the top and right